文件转换和变量替换参考

项目
04/05/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

某些任务（如 Azure 应用服务部署任务版本 3 及更高版本和 IIS Web 应用部署任务）允许用户基于指定环境配置包。这些任务使用 msdeploy.exe，它支持使用 parameters.xml 文件中的值替代 web.config 文件中的值。但是，文件转换和变量替换并不局限于 Web 应用文件。你可以将这些方法用于任何 XML 或 JSON 文件。

注意

用于 Azure Pipelines 的单独文件转换任务也支持文件转换和变量替换。可以使用文件转换任务对任何配置文件及参数文件应用文件转换和变量替换。

配置替换是在任务设置的“文件转换和变量替换选项”部分中指定的。转换和替换选项包括：

XML 转换
XML 变量替换
JSON 变量替换

任务运行时，首先对配置和参数文件执行 XML 转换、XML 变量替换和 JSON 变量替换。接下来，调用 msdeploy.exe，它使用 parameters.xml 文件替换 web.config 文件中的值。

XML 转换

XML 转换支持按照 Web.config 转换语法转换配置文件（*.config 文件），并基于 Web 程序包将部署到的环境。如果要添加、删除或修改不同环境的配置，此选项非常有用。转换将应用于其他配置文件，包括控制台或 Windows 服务应用程序配置文件（例如 FabrikamService.exe.config）。

配置转换文件命名约定

XML 转换将针对名为 *.Release.config 或 *.<stage>.config 的转换配置文件在 *.config 文件上运行，并将按以下顺序执行：

*.Release.config（例如，fabrikam.Release.config）
*.<stage>.config（例如，fabrikam.Production.config）

例如，如果程序包包含以下文件：

Web.config
Web.Debug.config
Web.Release.config
Web.Production.config

并且阶段名称是“Production”，将使用 Web.Release.config 对 Web.config 应用转换，后跟 Web.Production.config。

XML 转换示例

使用必要的配置和转换文件创建 Web 应用程序包。例如，使用以下配置文件：

配置文件

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="DefaultConnection"
         connectionString="Data Source=(LocalDb)\\MSDB;DbFilename=aspcore-local.mdf;" />
  </connectionStrings>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
  </appSettings>
  <system.web>
    <authentication mode="None" />
    <compilation targetFramework="4.5" debug="true" />
  </system.web>
</configuration>

转换文件

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <connectionStrings>
      <add name="MyDB"
           connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True"
           xdt:Transform="Insert" />
    </connectionStrings>
  <appSettings>
    <add xdt:Transform="Replace" xdt:Locator="Match(key)" key="webpages:Enabled" value="true" />
  </appSettings>
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
  </system.web>
</configuration>

此转换配置文件示例执行三项操作：

在 ConnectionStrings 元素内添加新的数据库连接字符串。
它修改 appSettings 元素内 Webpages:Enabled 值。
它从 System.Web 元素内的 compilation 元素中删除 debug 属性。

有关更多信息，请参阅用于使用 Visual Studio 的 Web 项目部署的 Web.config 转换语法

使用名为 Release 的阶段创建管发布道。
添加“Azure 应用服务部署”任务，并设置（勾选）“XML 转换”选项。
保存发布管道并启动新发布。

打开 Web.config 文件以查看来自 Web.Release.config 的转换。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="DefaultConnection"
         connectionString="Data Source=(LocalDb)\\MSDB;DbFilename=aspcore-local.mdf;" />
  <add name="MyDB"
       connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;Integrated Security=True" />
  </connectionStrings>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="true" />
  </appSettings>
  <system.web>
    <authentication mode="None" />
    <compilation targetFramework="4.5" />
  </system.web>
</configuration>

XML 转换说明

可以使用此方法创建默认包并将其部署到多个阶段。
仅当配置文件和转换文件位于指定包中的同一文件夹中时，XML 转换才会生效。
默认情况下，如果 <DependentUpon> 元素已存在于 *.csproj 文件中的转换文件中，则 MSBuild 会在生成 Web 程序包时应用转换。在这种情况下，“Azure 应用服务部署”任务将失败，因为没有对 Web.config 文件应用进一步的转换。因此，建议从所有转换文件中删除 <DependentUpon> 元素，以在使用 XML 转换时禁用任何生成时配置。

将每个转换文件的“生成操作”属性 (Web.config) 设置为“内容”，以便将文件复制到根文件夹。

...
<Content Include="Web.Debug.config">
   <DependentUpon>Web.config</DependentUpon>
</Content>
<Content Include="Web.Release.config">
   <DependentUpon>Web.config</DependentUpon>
</Content>
...

XML 变量替换

此功能使你能够修改 Web 程序包内配置文件（*.config 文件）和 XML 参数文件 (parameters.xml) 中的配置设置。这样，就可以根据要部署到的环境来配置同一个程序包。

变量替换仅对配置文件的 applicationSettings、appSettings、connectionStrings 和 configSections 元素生效。如果要在这些元素之外替换值，可以使用 (parameters.xml) 文件，但需要使用第三方管道任务来处理变量替换。

XML 变量替换示例

例如，考虑更改 Web.config 中的以下值的任务：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <configSection>
        <section name="entityFramework" />
    </configSection>
    <connectionStrings>
        <!-- Change connectionString in this line: --> 
        <add name="DefaultConnection"
             connectionString="Data Source=(LocalDB)\LocalDB;FileName=Local.mdf" />
    </connectionStrings>
    <appSettings>
        <add key="ClientValidationEnabled" value="true" />
        <add key="UnobstructiveJavascriptEnabled" value="true" />
        <!-- Change AdminUserName in this line: --> 
        <add key="AdminUserName" value="__AdminUserName__" />
        <!-- Change AdminPassword in this line: --> 
        <add key="AdminPassword" value="__AdminPassword__" />
    </appSettings>
    <entityFramework>
        <defaultConnectionFactory type="System.Data.Entity.LocalDbConnectionFactory">
            <parameters></parameters>
        </defaultConnectionFactory>
        <providers>
            <!-- Change invariantName in this line: --> 
            <provider invariantName="System.Data.SqlClient" type="System.Data.Entity.SqlServer" />
        </providers>
    </entityFramework>
</configuration>

使用名为 Release 的阶段创建管发布道。
添加“Azure 应用服务部署”任务，并设置（勾选）“XML 变量替换”选项。

在发布管道变量中定义所需的值：

名称	值	安全	范围
DefaultConnection	Data Source=(ProdDB)\MSSQLProdDB;AttachFileName=Local.mdf	否	发布
AdminUserName	ProdAdminName	否	发布
AdminPassword	[your-password]	是	发布
invariantName	System.Data.SqlClientExtension	否	发布

保存发布管道并启动新发布。

打开 Web.config 文件以查看变量替换。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <configSection>
        <section name="entityFramework" />
    </configSection>
    <connectionStrings>
        <add name="DefaultConnection"
             connectionString="Data Source=(ProdDB)\MSSQLProdDB;AttachFileName=Local.mdf" />
    </connectionStrings>
    <appSettings>
        <add key="ClientValidationEnabled" value="true" />
        <add key="UnobstructiveJavascriptEnabled" value="true" />
        <add key="AdminUserName" value="ProdAdminName" />
        <add key="AdminPassword" value="*password_masked_for_display*" />
    </appSettings>
    <entityFramework>
        <defaultConnectionFactory type="System.Data.Entity.LocalDbConnectionFactory">
            <parameters></parameters>
        </defaultConnectionFactory>
        <providers>
            <provider invariantName="System.Data.SqlClientExtension"
                      type="System.Data.Entity.SqlServer" />
        </providers>
    </entityFramework>
</configuration>

XML 变量替换说明

默认情况下，ASP.NET 应用程序具有默认的参数化连接属性。这些值仅在 Web 程序包内的 parameters.xml 文件中被替代。
由于替换发生在部署之前，因此用户可以使用 parameters.xml（在 Web 程序包内）或 setparameters 文件替代 Web.config 中的值。

JSON 变量替换

此功能替换 JSON 配置文件中的值。它使用与发布管道和阶段变量的名称相匹配的值替代指定的 JSON 配置文件（例如，appsettings.json）中的值。

要替换特定 JSON 文件中的变量，需提供 JSON 文件的换行符分隔列表。必须相对于根文件夹指定文件名。例如，如果程序包具有以下结构：

/WebPackage(.zip)
  /---- content
    /----- website
      /---- appsettings.json
      /---- web.config
      /---- [other folders] 
  /--- archive.xml
  /--- systeminfo.xml

并且要替换 appsettings.json 中的值，请输入相对于根文件夹的相对路；例如 content/website/appsettings.json。或者，使用通配符模式搜索特定的 JSON 文件。例如，**/appsettings.json 返回名为 appsettings.json 的文件的相对路径和名称。

JSON 变量替换示例

例如，考虑替代此 JSON 文件中的值的任务：

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Data Source=(LocalDb)\\MSDB;AttachDbFilename=aspcore-local.mdf;"
    },
    "DebugMode": "enabled",
    "DBAccess": {
      "Administrators": ["Admin-1", "Admin-2"],
      "Users": ["Vendor-1", "vendor-3"]
    },
    "FeatureFlags": {
      "Preview": [
        {
          "newUI": "AllAccounts"
        },
        {
          "NewWelcomeMessage": "Newusers"
        }
      ]
    }
  }
}

该任务替代 JSON 文件层次结构中的 ConnectionString、DebugMode、Users 值的第一个值和相应位置的 NewWelcomeMessage 的值。

经典
YAML

使用名为 Release 的阶段创建管发布道。
添加“Azure 应用服务部署”任务，并输入 JSON 文件的换行符分隔列表，以替换“JSON 变量替换”文本框中的变量值。文件名必须相对于根文件夹。可以使用通配符搜索 JSON 文件。例如：**/*.json 表示程序包内所有 JSON 文件中的替换值。

在发布管道或阶段变量中定义所需的替换值。

名称	值	安全	范围
Data.DebugMode	disabled	否	发布
Data.DefaultConnection.ConnectionString	Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;	否	发布
Data.DBAccess.Users.0	Admin-3	是	发布
Data.FeatureFlags.Preview.1.NewWelcomeMessage	AllAccounts	否	发布

保存发布管道并启动新发布。

转换后，JSON 将包含以下项：

{
  "Data": {
    "DefaultConnection": {
      "ConnectionString": "Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;"
    },
    "DebugMode": "disabled",
    "DBAccess": {
      "Administrators": ["Admin-1", "Admin-2"],
      "Users": ["Admin-3", "vendor-3"]
    },
    "FeatureFlags": {
      "Preview": [
        {
          "newUI": "AllAccounts"
        },
        {
          "NewWelcomeMessage": "AllAccounts"
        }
      ]
    }
  }
}
'''

以下 YAML 代码片段展示了 JSON 变量替换。

variables:
  Data.DebugMode: disabled
  Data.DefaultConnection.ConnectionString: 'Data Source=(prodDB)\MSDB;AttachDbFilename=prod.mdf;'
  Data.DBAccess.Users.0: Admin-3
  Data.FeatureFlags.Preview.1.NewWelcomeMessage: AllAccounts

# Update appsettings.json via FileTransform task.
- task: FileTransform@1
  displayName: 'File transformation: appsettings.json'
  inputs:
    folderPath: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip'
    targetFiles: '**/appsettings.json'
    fileType: json
  
# Deploy web app
- task: AzureWebApp@1
  inputs:
    azureSubscription: <Name of the Azure subscription>
    appName: <Name of the Azure WebApp>
    package: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip

JSON 变量替换说明

要替换文件嵌套级别中的值，请按层级顺序将名称与句点 (.) 连接在一起。
JSON 对象可能包含一个数组，可按索引引用数组中的值。例如，要替换上面所示的 Users 数组中的第一个值，请使用变量名称 DBAccess.Users.0。要更新 NewWelcomeMessage 中的值，请使用变量名称 FeatureFlags.Preview.1.NewWelcomeMessage。但是，文件转换任务能够转换 JSON 文件中的整个数组。还可以使用 DBAccess.Users = ["NewUser1","NewUser2","NewUser3"]。
JSON 变量替换仅支持字符串替换。
仅 UTF-8 和 UTF-16 LE 编码文件支持替换。
如果输入的文件规范与任何文件都不匹配，则任务将失败。
变量名称匹配区分大小写。
变量替换仅适用于对象层次结构中预定义的 JSON 键。它不会创建新键。
如果变量名称包含句点（“.”），转换将尝试在层次结构中查找项。例如，如果变量名称为 first.second.third，则转换过程将搜索：
```
"first" : {
  "second": {
    "third" : "value"
  }
}
```
以及 "first.second.third" : "value"。